home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / khelpmenu.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-10-08  |  7.9 KB  |  282 lines
  1. /*
  2.  * This file is part of the KDE Libraries
  3.  * Copyright (C) 1999-2000 Espen Sand (espen@kde.org)
  4.  *
  5.  * This library is free software; you can redistribute it and/or
  6.  * modify it under the terms of the GNU Library General Public
  7.  * License as published by the Free Software Foundation; either
  8.  * version 2 of the License, or (at your option) any later version.
  9.  *
  10.  * This library is distributed in the hope that it will be useful,
  11.  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.  * Library General Public License for more details.
  14.  *
  15.  * You should have received a copy of the GNU Library General Public License
  16.  * along with this library; see the file COPYING.LIB.  If not, write to
  17.  * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18.  * Boston, MA 02110-1301, USA.
  19.  *
  20.  */
  21.  
  22. #ifndef _KHELPMENU_H_
  23. #define _KHELPMENU_H_
  24.  
  25. #include <qobject.h>
  26. #include <qstring.h>
  27.  
  28. #include <kdelibs_export.h>
  29.  
  30. class KActionCollection;
  31. class KPopupMenu;
  32. class QWidget;
  33.  
  34. class KAboutData;
  35. class KAboutKDE;
  36. class KBugReport;
  37. class KDialogBase;
  38. class KHelpMenuPrivate;
  39.  
  40.  
  41. /**
  42.  * @short Standard %KDE help menu with dialog boxes.
  43.  *
  44.  * This class provides the standard %KDE help menu with the default "about"
  45.  * dialog boxes and help entry.
  46.  *
  47.  * This class is used in KMainWindow so
  48.  * normally you don't need to use this class yourself. However, if you
  49.  * need the help menu or any of its dialog boxes in your code that is
  50.  * not subclassed from KMainWindow you should use this class.
  51.  *
  52.  * The usage is simple:
  53.  *
  54.  * \code
  55.  * mHelpMenu = new KHelpMenu( this, <someText> );
  56.  * kmenubar->insertItem(i18n("&Help"), mHelpMenu->menu() );
  57.  * \endcode
  58.  *
  59.  * or if you just want to open a dialog box:
  60.  *
  61.  * \code
  62.  * mHelpMenu = new KHelpMenu( this, <someText> );
  63.  * connect( this, SIGNAL(someSignal()), mHelpMenu,SLOT(mHelpMenu->aboutKDE()));
  64.  * \endcode
  65.  *
  66.  * IMPORTANT:
  67.  * The first time you use KHelpMenu::menu(), a KPopupMenu object is
  68.  * allocated. Only one object is created by the class so if you call
  69.  * KHelpMenu::menu() twice or more, the same pointer is returned. The class
  70.  * will destroy the popupmenu in the destructor so do not delete this
  71.  * pointer yourself.
  72.  *
  73.  * The KHelpMenu object will be deleted when its parent is destroyed but you
  74.  * can delete it yourself if you want. The code below will always work.
  75.  *
  76.  * \code
  77.  * MyClass::~MyClass()
  78.  * {
  79.  *   delete mHelpMenu;
  80.  * }
  81.  * \endcode
  82.  *
  83.  *
  84.  * Using your own "about application" dialog box:
  85.  *
  86.  * The standard "about application" dialog box is quite simple. If you
  87.  * need a dialog box with more functionality you must design that one
  88.  * yourself. When you want to display the dialog you can choose one of
  89.  * two methods. Common for both is that you must make a help menu object
  90.  * with no text argument If the text is missing the default dialog box
  91.  * will not be displayed:
  92.  *
  93.  * Example 1 Using showAboutApplication signal (preferred)
  94.  * \code
  95.  *
  96.  * void MyClass::myFunc()
  97.  * {
  98.  *   ..
  99.  *   KHelpMenu *helpMenu = new KHelpMenu( this );
  100.  *   connect( helpMenu, SIGNAL(showAboutApplication()),
  101.  *          this, SLOT(myDialogSlot()));
  102.  *   ..
  103.  * }
  104.  *
  105.  * void MyClass::myDialogSlot()
  106.  * {
  107.  *   <activate your custom dialog>
  108.  * }
  109.  * \endcode
  110.  *
  111.  *
  112.  * Example 2 Old style - connecting directly to the menu entry.
  113.  * \code
  114.  *
  115.  * void MyClass::myFunc()
  116.  * {
  117.  *   KHelpMenu *helpMenu = new KHelpMenu( this );
  118.  *   KPopupMenu *help = mHelpMenu->menu();
  119.  *   help->connectItem( KHelpMenu::menuAboutApp, this, SLOT(myDialogSlot()) );
  120.  * }
  121.  *
  122.  * void MyClass::myDialogSlot()
  123.  * {
  124.  *   <activate your custom dialog>
  125.  * }
  126.  * \endcode
  127.  *
  128.  * @author Espen Sand (espen@kde.org)
  129.  */
  130.  
  131. class KDEUI_EXPORT KHelpMenu : public QObject
  132. {
  133.   Q_OBJECT
  134.  
  135.   public:
  136.     enum MenuId
  137.     {
  138.       menuHelpContents = 0,
  139.       menuWhatsThis = 1,
  140.       menuAboutApp = 2,
  141.       menuAboutKDE = 3,
  142.       menuReportBug = 4,
  143.       menuSwitchLanguage = 5
  144.     };
  145.  
  146.     /**
  147.      * Constructor.
  148.      *
  149.      * @param parent The parent of the dialog boxes. The boxes are modeless
  150.      *        and will be centered with respect to the parent.
  151.      * @param aboutAppText User definable string that is used in the
  152.      *        application specific dialog box. Note: The help menu will
  153.      *        not open this dialog box if you don't define a string. See
  154.      *        showAboutApplication() for more information.
  155.      * @param showWhatsThis Decides whether a "Whats this" entry will be
  156.      *        added to the dialog.
  157.      *
  158.      */
  159.     KHelpMenu( QWidget *parent=0, const QString &aboutAppText=QString::null,
  160.            bool showWhatsThis=true );
  161.  
  162.     /**
  163.      * Constructor.
  164.      *
  165.      * This alternative constructor is mainly useful if you want to
  166.      * overide the standard actions (aboutApplication(), aboutKDE(),
  167.      * helpContents(), reportBug, and optionally whatsThis).
  168.      *
  169.      * @param parent The parent of the dialog boxes. The boxes are modeless
  170.      *        and will be centered with respect to the parent.
  171.      * @param aboutData User and app data used in the About app dialog
  172.      * @param showWhatsThis Decides whether a "Whats this" entry will be
  173.      *        added to the dialog.
  174.      * @param actions KActionCollection that is used instead of the
  175.      *        standard actions.
  176.      *
  177.      */
  178.     KHelpMenu( QWidget *parent, const KAboutData *aboutData,
  179.            bool showWhatsThis=true, KActionCollection *actions = 0 );
  180.  
  181.     /**
  182.      * Destructor
  183.      *
  184.      * Destroys dialogs and the menu pointer retuned by menu
  185.      */
  186.     ~KHelpMenu();
  187.  
  188.     /**
  189.      * Returns a popup menu you can use in the menu bar or where you
  190.      * need it.
  191.      *
  192.      * Note: This method will only create one instance of the menu. If
  193.      * you call this method twice or more the same pointer is returned
  194.      */
  195.     KPopupMenu *menu();
  196.  
  197.   public slots:
  198.     /**
  199.      * Opens the help page for the application. The application name is
  200.      * used as a key to determine what to display and the system will attempt
  201.      * to open \<appName\>/index.html.
  202.      */
  203.     void appHelpActivated();
  204.  
  205.     /**
  206.      * Activates What's This help for the application.
  207.      */
  208.     void contextHelpActivated();
  209.  
  210.     /**
  211.      * Opens an application specific dialog box. The dialog box will display
  212.      * the string that was defined in the constructor. If that string was
  213.      * empty the showAboutApplication() is emitted instead.
  214.      */
  215.     void aboutApplication();
  216.  
  217.     /**
  218.      * Opens the standard "About KDE" dialog box.
  219.      */
  220.     void aboutKDE();
  221.  
  222.     /**
  223.      * Opens the standard "Report Bugs" dialog box.
  224.      */
  225.     void reportBug();
  226.     
  227.     /**
  228.      * Opens changing default application language dialog box.
  229.      */
  230.     void switchApplicationLanguage();
  231.  
  232.   private slots:
  233.     /**
  234.      * Connected to the menu pointer (if created) to detect a delete
  235.      * operation on the pointer. You should not delete the pointer in your
  236.      * code yourself. Let the KHelpMenu destructor do the job.
  237.      */
  238.     void menuDestroyed();
  239.  
  240.     /**
  241.      * Connected to the dialogs (about kde and bug report) to detect
  242.      * when they are finished.
  243.      */
  244.     void dialogFinished();
  245.  
  246.     /**
  247.      * This slot will delete a dialog (about kde or bug report) if the
  248.      * dialog pointer is not zero and the the dialog is not visible. This
  249.      * slot is activated by a one shot timer started in dialogHidden
  250.      */
  251.     void timerExpired();
  252.  
  253.   signals:
  254.     /**
  255.      * This signal is emitted from aboutApplication() if no
  256.      * "about application" string has been defined. The standard
  257.      * application specific dialog box that is normally activated in
  258.      * aboutApplication() will not be displayed when this signal
  259.      * is emitted.
  260.      */
  261.     void showAboutApplication();
  262.  
  263.   private:
  264.     KPopupMenu   *mMenu;
  265.     KDialogBase  *mAboutApp;
  266.     KAboutKDE    *mAboutKDE;
  267.     KBugReport   *mBugReport;
  268.  
  269.     QString      mAboutAppText;
  270.     QWidget      *mParent;
  271.  
  272.     bool         mShowWhatsThis;
  273.  
  274.   protected:
  275.     virtual void virtual_hook( int id, void* data );
  276.   private:
  277.     KHelpMenuPrivate *d;
  278. };
  279.  
  280.  
  281. #endif
  282.